Release 10.1A: OpenEdge Development:
Progress 4GL Reference

SET-OUTPUT-DESTINATION( ) method

Defines the target of the XML document that the SAX-writer object will create.

Return Type: LOGICAL

Applies to: SAX-writer object handle

Syntax

SET-OUTPUT-DESTINATION ( mode, { file | stream | memptr | longchar } )

mode

A character expression that evaluates to one of the following: “FILE”, “STREAM”, “MEMPTR”, or “LONGCHAR”. The mode indicates whether the XML target is a file, a stream, a MEMPTR, or a LONGCHAR variable.

file

A character expression that represents the name of a file. You can specify a pathname relative to the current directory or an absolute pathname.

stream

A character expression that represents the name of a 4GL stream. If stream is "", Progress saves the document to the unnamed stream of the 4GL session.

memptr

A MEMPTR variable that the XML document will be written to. The MEMPTR will be overwritten and the new size of the MEMPTR variable will match the size of the XML text.

longchar

A LONGCHAR variable that the XML document will be written to. The LONGCHAR will be overwritten and the new size of the LONGCHAR variable will match the size of the XML text.

When writing an XML document to a LONGCHAR variable, Progress writes the LONGCHAR variable in the code page of the XML document as determined by the XML document’s ENCODING attribute. If the ENCODING attribute is not set, the LONGCHAR variable is saved in UTF-8.

If the LONGCHAR variable’s code page is fixed (that is, set using the FIX-CODEPAGE function), the code page must be equivalent to the encoding specified in the XML document’s ENCODING attribute. If not, the START-DOCUMENT( ) method returns an error and the XML document is not saved to the LONGCHAR variable.

Use this method to set the output destination, which is where the object will write the XML document. This method must be called before you call any of the writing methods or they will raise errors. You can only call this method when the object’s WRITE-STATUS property is SAX-WRITE-IDLE or SAX-WRITE-COMPLETE. In other words, you cannot set a new output destination while the SAX-writer object is currently writing XML. This method fails and generates an error message if it is called while writing.

The SET-OUTPUT-DESTINATION method does not check if the specified destination is valid. If does not check whether a MEMPTR or LONGCHAR variable is usable, and it does not check whether a file location or stream is accessible. This destination is checked at run time by the START-DOCUMENT method.

When writing to a MEMPTR or LONGCHAR, the method deletes the previous contents and allocates new memory. For example, writing to a MEMPTR is the logical equivalent of using SET-SIZE based upon the document size after calling END-DOCUMENT. This is the same way that the X-document object handles memory.